Kanzi  3.9.9
Kanzi Engine C++ API
kanzi::NodeEffectRenderer2D Class Referenceabstract

Node effect renderer class. More...

#include <kanzi/core.ui/node/node_effect_renderer2d.hpp>

Inheritance diagram for kanzi::NodeEffectRenderer2D:
[legend]

Classes

struct  EffectPass
 Effect pass configuration. More...
 
struct  EffectRenderState
 Render state configuration to use with an effect pass. More...
 

Public Member Functions

void applyEffect (Renderer3D &renderer, CompositionStack &compositionStack, CompositionManager *compositionManager, const Matrix3x3 &worldTransform, const CompositionContentRequirements &requirements, TextureSharedPtr sourceContent)
 Applies the effect on the source content provided as texture. More...
 
void beginEffect (Renderer3D &renderer, CompositionStack &compositionStack, CompositionManager *compositionManager, const Matrix3x3 &worldTransform, const CompositionContentRequirements &requirements)
 Begins the effect. More...
 
void blitEffect (Renderer3D &renderer, CompositionStack &compositionStack, CompositionManager *compositionManager, const QuadDescription &effectQuad, const Matrix3x3 &transform, const Matrix4x4 *perspectiveMatrix, const Matrix4x4 *projectionMatrix, int blendMode, bool needsClear)
 Blits the effect to the current framebuffer. More...
 
void endEffect (Renderer3D &renderer, CompositionStack &compositionStack, CompositionManager *compositionManager)
 Ends the effect. More...
 
NodeEffect2DSharedPtr getEffect () const
 Get NodeEffect2D instance where this renderer has been instantiated from. More...
 
size_t getEffectPassCount () const
 Gets the number of effect passes. More...
 
bool isLayeredOnTop () const
 Whether a compatible effect renders logically on top of its source content. More...
 
bool isRenderEffectOnlyEnabled () const
 Whether the effect only mode is enabled. More...
 
void restoreResources ()
 Restores resources after the rendering context has been lost. More...
 
void setRenderEffectOnly (bool renderEffectOnly)
 Sets the render effect only mode. More...
 
virtual bool supportsBlitBlendMode (int blendMode)
 Whether the effect is compatible with a given blend mode. More...
 
virtual ~NodeEffectRenderer2D ()
 Declare NodeEffectRenderer2D as not movable nor copyable. More...
 

Protected Types

using EffectPassContainer = vector< EffectPass >
 Container for effect passes. More...
 

Protected Member Functions

EffectPassaddEffectPass ()
 Adds an effect pass and gets a reference to that pass. More...
 
virtual void beginEffectOverride (Renderer3D &renderer, CompositionStack &compositionStack, CompositionManager *compositionManager, const Matrix3x3 &worldTransform, const CompositionContentRequirements &requirements)=0
 Begin effect. More...
 
void beginInitialEffectPass (Renderer3D &renderer, CompositionStack &compositionStack, CompositionManager *compositionManager, const CompositionContentRequirements &requirements)
 Begins the initial effect pass (effect pass at index 0). More...
 
virtual void blitEffectOverride (Renderer3D &renderer, CompositionStack &compositionStack, CompositionManager *compositionManager, const QuadDescription &effectQuad, const Matrix3x3 &transform, const Matrix4x4 *perspectiveMatrix, const Matrix4x4 *projectionMatrix, int blendMode, bool needsClear)=0
 Blit effect to current framebuffer. More...
 
void blitEffectPass (int effectPassIndex, Renderer3D &renderer, CompositionStack &compositionStack, CompositionManager *compositionManager, const QuadDescription &effectQuad, const Matrix3x3 &transform, const Matrix4x4 *perspectiveMatrix, const Matrix4x4 *projectionMatrix, int blendMode, bool needsClear)
 Blits the effect pass and handles the perspective transform if necessary. More...
 
void blitFinalEffectPass (Renderer3D &renderer, CompositionStack &compositionStack, CompositionManager *compositionManager, const QuadDescription &effectQuad, const Matrix3x3 &transform, const Matrix4x4 *perspectiveMatrix, const Matrix4x4 *projectionMatrix, int blendMode, bool needsClear)
 Blits the final effect pass, whose index is getEffectPassCount() - 1, and handles the perspective transform if necessary. More...
 
void blitIntermediateEffectPass (int effectPassIndex, Renderer3D &renderer, CompositionStack &compositionStack, CompositionManager *compositionManager)
 Blits the intermediate effect pass. More...
 
void clearRenderTarget (Renderer3D &renderer, CompositionStack &compositionStack, TextureSharedPtr texture, ColorRGBA clearColor)
 Clears the render target texture with a given color. More...
 
void clearRenderTarget (Renderer3D &renderer, CompositionStack &compositionStack, NativeFramebufferHandle framebufferHandle, ColorRGBA clearColor)
 Clears the native framebuffer with a given color. More...
 
void configureInitialEffectPass (Vector2 sourceContentSize)
 Configures the initial effect pass. More...
 
virtual void endEffectOverride (Renderer3D &renderer, CompositionStack &compositionStack, CompositionManager *compositionManager)=0
 End effect. More...
 
void endInitialEffectPass (CompositionStack &compositionStack)
 Ends the initial effect pass, whose index is 0. More...
 
void finalizeEffectPasses ()
 Finalizes the effect passes. More...
 
Vector2 getEffectInputTexelSize (int effectPassIndex, int inputIndex)
 Gets the texel size of the input effect pass texture in texture coordinates. More...
 
EffectPassgetEffectPass (int index)
 Gets a reference to the effect pass at a given index. More...
 
int getLastEffectPassIndex () const
 Gets the index of the last effect pass. More...
 
bool isInitialPassRenderTargetTemporary () const
 Whether the initial pass render target is temporary. More...
 
 NodeEffectRenderer2D (NodeEffect2DSharedPtr nodeEffect)
 Constructor. More...
 
virtual void onRenderEffectOnlyChanged ()
 Kanzi calls this when the render effect only mode changes. More...
 
void releaseEffectPassInputRenderTargets (EffectPass &currentEffectPass, CompositionManager *compositionManager)
 Releases those temporary render targets used by input that have EffectPass::Input::releaseRenderTarget set to true. More...
 
void removeAllEffectPasses ()
 Removes all user-added effect passes, but leaves the internal initial effect pass. More...
 
virtual void restoreResourcesOverride ()=0
 Restore resource after rendering context has been lost. More...
 
void setLayeredOnTop (bool layeredOnTop)
 Sets whether the effect is layered on top of the source content. More...
 

Static Protected Attributes

static constexpr int InitialEffectPassIndex
 Effect pass index for the initial pass. More...
 

Detailed Description

Node effect renderer class.

See also
NodeEffect2D, NodeEffectPrefab2D, NodeEffectTemplate2D
Since
Kanzi 3.9.0

Member Typedef Documentation

Container for effect passes.

Constructor & Destructor Documentation

virtual kanzi::NodeEffectRenderer2D::~NodeEffectRenderer2D ( )
virtual

Declare NodeEffectRenderer2D as not movable nor copyable.

Destructor.

kanzi::NodeEffectRenderer2D::NodeEffectRenderer2D ( NodeEffect2DSharedPtr  nodeEffect)
explicitprotected

Constructor.

Parameters
nodeEffectNodeEffect2D instance associated with this renderer.

Member Function Documentation

NodeEffect2DSharedPtr kanzi::NodeEffectRenderer2D::getEffect ( ) const

Get NodeEffect2D instance where this renderer has been instantiated from.

void kanzi::NodeEffectRenderer2D::beginEffect ( Renderer3D renderer,
CompositionStack compositionStack,
CompositionManager compositionManager,
const Matrix3x3 worldTransform,
const CompositionContentRequirements requirements 
)

Begins the effect.

Call this function before rendering the source content for the effect.

Parameters
rendererRenderer to use.
compositionStackCompositionStack to use.
compositionManagerCompositionManager to use.
worldTransform2D affine world transform used by the node.
requirementsRequirements for the effect contents.
Since
Kanzi 3.9.7 bundle requirements to struct.
void kanzi::NodeEffectRenderer2D::endEffect ( Renderer3D renderer,
CompositionStack compositionStack,
CompositionManager compositionManager 
)

Ends the effect.

Call this function after rendering the source content for the effect.

Parameters
rendererRenderer to use.
compositionStackCompositionStack to use.
compositionManagerCompositionManager to use.
void kanzi::NodeEffectRenderer2D::applyEffect ( Renderer3D renderer,
CompositionStack compositionStack,
CompositionManager compositionManager,
const Matrix3x3 worldTransform,
const CompositionContentRequirements requirements,
TextureSharedPtr  sourceContent 
)

Applies the effect on the source content provided as texture.

This is an alternative to beginEffect() and endEffect(). Call either applyEffect() or beginEffect() followed by endEffect(). Do not mix them during the application of an effect.

Parameters
rendererRenderer to use.
compositionStackCompositionStack to use.
compositionManagerCompositionManager to use.
worldTransform2D affine world transform used by the node.
requirementsRequirements for the effect contents.
sourceContentSource content as a texture. You can use this in place of the initial effect pass. The texture must include a one-pixel wide transparent black padding around the content.
Since
Kanzi 3.9.8.
void kanzi::NodeEffectRenderer2D::blitEffect ( Renderer3D renderer,
CompositionStack compositionStack,
CompositionManager compositionManager,
const QuadDescription effectQuad,
const Matrix3x3 transform,
const Matrix4x4 perspectiveMatrix,
const Matrix4x4 projectionMatrix,
int  blendMode,
bool  needsClear 
)

Blits the effect to the current framebuffer.

Call this function after NodeEffectRenderer2D::endEffect when you want to blit the effect to screen. You can use this function to implement perspective projection, if you provide the relevant matrices.

Parameters
rendererRenderer to use.
compositionStackCompositionStack to use.
compositionManagerCompositionManager to use.
effectQuadPotentially clipped effect quad honoring the NodeEffect2D::getEffectQuadPadding to use for rendering the effect.
transform2D affine transform to use for rendering the effect quad.
perspectiveMatrixOptional perspective matrix to use.
projectionMatrixOptional projection matrix to use when rendering with perspective transform.
blendModeThe blend mode to use for the effect blit.
needsClearWhether the current render target needs to be cleared before rendering.
Since
Kanzi 3.9.1 data type of the blendMode parameter changed from GraphicsBlendMode to int.
void kanzi::NodeEffectRenderer2D::restoreResources ( )

Restores resources after the rendering context has been lost.

size_t kanzi::NodeEffectRenderer2D::getEffectPassCount ( ) const

Gets the number of effect passes.

Returns
The number of effect passes.
void kanzi::NodeEffectRenderer2D::setRenderEffectOnly ( bool  renderEffectOnly)

Sets the render effect only mode.

When enabled, compatible effects render only the effect without the source content.

Parameters
renderEffectOnlyWhether to render only the effect. Default is false.
Since
Kanzi 3.9.8.
bool kanzi::NodeEffectRenderer2D::isRenderEffectOnlyEnabled ( ) const

Whether the effect only mode is enabled.

Returns
If effect only mode is enabled, true, otherwise false.
Since
Kanzi 3.9.8.
bool kanzi::NodeEffectRenderer2D::isLayeredOnTop ( ) const

Whether a compatible effect renders logically on top of its source content.

Returns
If effect is rendered on top of its source content, true, otherwise false.
Since
Kanzi 3.9.8.
virtual bool kanzi::NodeEffectRenderer2D::supportsBlitBlendMode ( int  blendMode)
virtual

Whether the effect is compatible with a given blend mode.

See blitEffect(). If an effect is not compatible with a blend mode, you must composite that effect and use the blend mode when blitting the composite. All effects are compatible with the GraphicsBlendModePremultipliedAlpha blend mode.

Parameters
blendModeThe blend mode to test.
Returns
If the effect is compatible with the blend mode, true, otherwise false.
Since
Kanzi 3.9.8.

Reimplemented in kanzi::OutlineEffectRenderer2D, and kanzi::ShadowEffectRenderer2D.

virtual void kanzi::NodeEffectRenderer2D::beginEffectOverride ( Renderer3D renderer,
CompositionStack compositionStack,
CompositionManager compositionManager,
const Matrix3x3 worldTransform,
const CompositionContentRequirements requirements 
)
protectedpure virtual

Begin effect.

Should be called before the source content for the effect is rendered.

Parameters
rendererRenderer to use.
compositionStackCompositionStack to use.
compositionManagerCompositionManager to use.
worldTransform2D affine world transform used by the node.
requirementsRequirements for the effect contents.
Since
Kanzi 3.9.7 bundle requirements to struct.

Implemented in kanzi::OutlineEffectRenderer2D.

virtual void kanzi::NodeEffectRenderer2D::endEffectOverride ( Renderer3D renderer,
CompositionStack compositionStack,
CompositionManager compositionManager 
)
protectedpure virtual

End effect.

Should be called after the source content for the effect has been rendered.

Parameters
rendererRenderer to use.
compositionStackCompositionStack to use.
compositionManagerCompositionManager to use.

Implemented in kanzi::OutlineEffectRenderer2D.

virtual void kanzi::NodeEffectRenderer2D::blitEffectOverride ( Renderer3D renderer,
CompositionStack compositionStack,
CompositionManager compositionManager,
const QuadDescription effectQuad,
const Matrix3x3 transform,
const Matrix4x4 perspectiveMatrix,
const Matrix4x4 projectionMatrix,
int  blendMode,
bool  needsClear 
)
protectedpure virtual

Blit effect to current framebuffer.

Should after NodeEffectRenderer2D::endEffect when the effect should be blitted to screen. Can be used to implement perspective projection if relevant matrices are provided.

Parameters
rendererRenderer to use.
compositionStackCompositionStack to use.
compositionManagerCompositionManager to use.
effectQuadPotentially clipped effect quad honoring the NodeEffect2D::getEffectQuadPadding to use for rendering the effect.
transform2D affine transform to use for rendering the effect quad.
perspectiveMatrixOptional perspective matrix to use.
projectionMatrixOptional projection matrix to use when rendering with perspective transform.
blendModeThe blend mode to use for the effect blit.
needsClearWhether the current render target needs to be cleared before rendering.
Since
Kanzi 3.9.1 data type of the blendMode parameter changed from GraphicsBlendMode to int.

Implemented in kanzi::OutlineEffectRenderer2D.

virtual void kanzi::NodeEffectRenderer2D::restoreResourcesOverride ( )
protectedpure virtual

Restore resource after rendering context has been lost.

Implemented in kanzi::OutlineEffectRenderer2D.

virtual void kanzi::NodeEffectRenderer2D::onRenderEffectOnlyChanged ( )
protectedvirtual

Kanzi calls this when the render effect only mode changes.

Reimplemented in kanzi::OutlineEffectRenderer2D.

void kanzi::NodeEffectRenderer2D::clearRenderTarget ( Renderer3D renderer,
CompositionStack compositionStack,
TextureSharedPtr  texture,
ColorRGBA  clearColor 
)
protected

Clears the render target texture with a given color.

Parameters
rendererRenderer3D to use.
compositionStackCompositionStack to use.
textureRender target texture to clear.
clearColorColor to use for the clear.
void kanzi::NodeEffectRenderer2D::clearRenderTarget ( Renderer3D renderer,
CompositionStack compositionStack,
NativeFramebufferHandle  framebufferHandle,
ColorRGBA  clearColor 
)
protected

Clears the native framebuffer with a given color.

Parameters
rendererRenderer3D to use.
compositionStackCompositionStack to use.
framebufferHandleFramebuffer handle to use.
clearColorColor to use for the clear.
EffectPass& kanzi::NodeEffectRenderer2D::addEffectPass ( )
protected

Adds an effect pass and gets a reference to that pass.

Adding an effect pass invalidates references to previously added effect passes. You must add at least two effect passes. The first pass renders the contents into a render target texture, and the last pass blits the effect result.

Returns
EffectPass reference to the just added effect pass.
int kanzi::NodeEffectRenderer2D::getLastEffectPassIndex ( ) const
protected

Gets the index of the last effect pass.

Returns
The index of the last effect pass or InitialEffectPassIndex if there are no effect passes added by user.
EffectPass& kanzi::NodeEffectRenderer2D::getEffectPass ( int  index)
protected

Gets a reference to the effect pass at a given index.

Parameters
indexIndex of the effect pass.
Returns
Reference to EffectPass instance at the given index.
void kanzi::NodeEffectRenderer2D::removeAllEffectPasses ( )
protected

Removes all user-added effect passes, but leaves the internal initial effect pass.

void kanzi::NodeEffectRenderer2D::finalizeEffectPasses ( )
protected

Finalizes the effect passes.

Call this function after you have added and configured all effect passes. This function sets EffectPass::Input::releaseRenderTarget and in debug build checks whether all render pass outputs are in use.

void kanzi::NodeEffectRenderer2D::beginInitialEffectPass ( Renderer3D renderer,
CompositionStack compositionStack,
CompositionManager compositionManager,
const CompositionContentRequirements requirements 
)
protected

Begins the initial effect pass (effect pass at index 0).

Parameters
rendererRenderer to use.
compositionStackCompositionStack to use.
compositionManagerCompositionManager to use.
requirementsRequirements for the effect contents.
Since
Kanzi 3.9.7 bundle requirements to struct.
void kanzi::NodeEffectRenderer2D::endInitialEffectPass ( CompositionStack compositionStack)
protected

Ends the initial effect pass, whose index is 0.

Parameters
compositionStackCompositionStack to use.
void kanzi::NodeEffectRenderer2D::blitIntermediateEffectPass ( int  effectPassIndex,
Renderer3D renderer,
CompositionStack compositionStack,
CompositionManager compositionManager 
)
protected

Blits the intermediate effect pass.

If intermediate effect passes exist, blit them in order starting from index 1 to getEffectPassCount() - 2.

Parameters
effectPassIndexIndex of the effect pass to use.
rendererRenderer to use.
compositionStackCompositionStack to use.
compositionManagerCompositionManager to use.
void kanzi::NodeEffectRenderer2D::blitFinalEffectPass ( Renderer3D renderer,
CompositionStack compositionStack,
CompositionManager compositionManager,
const QuadDescription effectQuad,
const Matrix3x3 transform,
const Matrix4x4 perspectiveMatrix,
const Matrix4x4 projectionMatrix,
int  blendMode,
bool  needsClear 
)
protected

Blits the final effect pass, whose index is getEffectPassCount() - 1, and handles the perspective transform if necessary.

Parameters
rendererRenderer to use.
compositionStackCompositionStack to use.
compositionManagerCompositionManager to use.
effectQuadPotentially clipped effect quad honoring the NodeEffect2D::getEffectQuadPadding to use for rendering the effect.
transform2D affine transform to use for rendering the effect quad.
perspectiveMatrixOptional perspective matrix to use.
projectionMatrixOptional projection matrix to use when rendering with perspective transform.
blendModeThe blend mode to use for the effect blit.
needsClearWhether the current render target needs to be cleared before rendering.
Since
Kanzi 3.9.1 data type of the blendMode parameter changed from GraphicsBlendMode to int.
void kanzi::NodeEffectRenderer2D::blitEffectPass ( int  effectPassIndex,
Renderer3D renderer,
CompositionStack compositionStack,
CompositionManager compositionManager,
const QuadDescription effectQuad,
const Matrix3x3 transform,
const Matrix4x4 perspectiveMatrix,
const Matrix4x4 projectionMatrix,
int  blendMode,
bool  needsClear 
)
protected

Blits the effect pass and handles the perspective transform if necessary.

Parameters
effectPassIndexIndex of the effect pass to use.
rendererRenderer to use.
compositionStackCompositionStack to use.
compositionManagerCompositionManager to use.
effectQuadPotentially clipped effect quad honoring the NodeEffect2D::getEffectQuadPadding to use for rendering the effect.
transform2D affine transform to use for rendering the effect quad.
perspectiveMatrixOptional perspective matrix to use.
projectionMatrixOptional projection matrix to use when rendering with perspective transform.
blendModeThe blend mode to use for the effect blit.
needsClearWhether the current render target needs to be cleared before rendering.
Since
Kanzi 3.9.8
Vector2 kanzi::NodeEffectRenderer2D::getEffectInputTexelSize ( int  effectPassIndex,
int  inputIndex 
)
protected

Gets the texel size of the input effect pass texture in texture coordinates.

You can call this function only after the source effect pass has obtained a valid render target.

Parameters
effectPassIndexEffect pass index.
inputIndexInput index.
Returns
Size of texel in texture coordinates.
void kanzi::NodeEffectRenderer2D::releaseEffectPassInputRenderTargets ( EffectPass currentEffectPass,
CompositionManager compositionManager 
)
protected

Releases those temporary render targets used by input that have EffectPass::Input::releaseRenderTarget set to true.

Parameters
currentEffectPassReference to the effect pass whose referenced render targets to release if necessary.
compositionManagerCompositionManager used to get the temporary render targets.
bool kanzi::NodeEffectRenderer2D::isInitialPassRenderTargetTemporary ( ) const
protected

Whether the initial pass render target is temporary.

See applyEffect().

Returns
If the initial pass used a temporary render target, true, otherwise false.
Since
Kanzi 3.9.8
void kanzi::NodeEffectRenderer2D::configureInitialEffectPass ( Vector2  sourceContentSize)
protected

Configures the initial effect pass.

Parameters
sourceContentSizeSize of the source content.
Since
Kanzi 3.9.8
void kanzi::NodeEffectRenderer2D::setLayeredOnTop ( bool  layeredOnTop)
protected

Sets whether the effect is layered on top of the source content.

Parameters
layeredOnTopIf layered on top of the source content, true, otherwise false.
Since
Kanzi 3.9.8

Member Data Documentation

constexpr int kanzi::NodeEffectRenderer2D::InitialEffectPassIndex
staticprotected

Effect pass index for the initial pass.


The documentation for this class was generated from the following file: